As a developer, the Open Food Facts API allows you to get information and contribute to the products database. You can create great apps to help people make better food choices and also provide data to enhance the database. Check out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses
The data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative. Therefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the WRITE API.
You can use the OFF API for production cases, as long as 1 API call equals 1 real scan by a user.
You can either use the global domain (https://world.openfoodfacts.org) or the local domains (https://fr.openfoodfacts.org, https://en.openfoodfacts.org, …) for your API queries.
The Open Food Facts base endpoint is: https://world.openfoodfacts.org
The current version of the API is 0.
READ and SEARCH operations
No authentication is required.
However, you have to add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.
For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com
WRITE operations
No authentication is required for adding new products or adding images.
Basic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.
Parameters
* user_id: YourUserID
* password: YourPassword
You can do READ/SEARCH/WRITE operations using the production server. To make tests for WRITE operations, use https://world.openfoodfacts.net (User:off, Password:off).
Use the SSL version of the API: https://world.openfoodfacts.org
Disclaimer: The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.
The API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls.
For more information, see: https://world.openfoodfacts.org/data
The API development is in progress. This has several implications:
_t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)_datetime are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ_tags are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)_100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of productDo not hesitate to file a bug if you find an issue in the API or need an improvement. You can fill out the issue report on GitHub:
It is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. They are available at:
API Redesign: The API is far from perfect. It’s been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.
READ requests allow you to retrieve the nutritional data of a product with a barcode.
GET https://[countrycode].openfoodfacts.org/api/v0/product/[barcode].json
GET https://world.openfoodfacts.org/api/v0/product/737628064502.json
Note: You can find a list of supported parameters and an example of a full JSON response in the Parameters section.
No authentication is required for READ operations.
However, you have to add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.
For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com
GET requests allow you to make two types of calls: READ and SEARCH. This scenario describes how to make GET READ calls to retrieve the nutritional data of products with a barcode.
Meet Dave. Dave is an active Open Food Facts contributor and a developer who wants to build HealthyFoodChoices, an Android app aimed at concious consumers that buy healthy products.
HealthyFoodChoices will provide information on healthy foods available in the place where their users live. The users can narrow down the results by applying different filters and save their search criteria so that the app shows them the products that match their preferences next time they use it.
To identify the potential users’ needs, Dave has met with some concious consumers. Anna is one of them. Anna doesn’t drink soda, but her nephew does. He will visit her soon, and she wants to compare the nutrition facts of two cola brands, and its variants (diet, zero, and so on) to decide which one to buy. Dave wants his app to make an API call to provide her with this information.
To make the API query that returns the products that might be interesting for Anna, Dave doesn’t need to authenticate. However, he has to add a User-Agent HTTP Header with the name of his app, the version, system and a url (if any), not to be blocked by mistake.
In this case, that would be: User-Agent: HealthyFoodChoices - Android - Version 1.0
Since Anna lives in NY, Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).
The country code determines that only the products sold in the US are displayed. The language of the interface for the country code us is English.
In this case:
The current version number of the Open Food Facts API is v0.
https://us.openfoodfacts.org/api/v0
After the version number, the word “product”, followed by its barcode must be added:
https://us.openfoodfacts.org/api/v0/product/ The app will provide Anna with information about additives, sugars and nutriscore of different types of colas, to help her make her purchase decision. Anna selects the products she wants to compare in the application (Coca-Cola, Pepsi, Coca-Cola diet, Coca-Cola zero and Pepsi diet). The app retrieves the corresponding barcodes and makes the following calls: Pepsico Pepsi Cola Soda:
https://us.openfoodfacts.org/api/v0/product/01223004 Coca-Cola Classic Coke Soft Drink
https://us.openfoodfacts.org/api/v0/product/04963406 Diet Pepsi
https://us.openfoodfacts.org/api/v0/product/069000019832 Coca-Cola Zero
https://us.openfoodfacts.org/api/v0/product/5000112519945Example Request
URL: https://world.openfoodfacts.org/api/v0/product/04963406
Headers
Key Value Description Content-Type application/x-www-form-urlencoded Example Response
Body
{
"status_verbose": "product found",
"product": {
"last_edit_dates_tags": [
"2018-10-21",
"2018-10",
"2018"
],
"pnns_groups_1": "Beverages",
"nova_group_debug": " -- categories/en:sodas : 3 -- additives/en:e150c : 4",
"ingredients_n": 6,
"completeness": 0.8,
"image_thumb_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.100.jpg",
"additives_n": 2,
"packaging": "can - metal",
"ingredients_from_palm_oil_n": 0,
"codes_tags": [
"code-8",
"04963406",
"0496340x",
"049634xx",
"04963xxx",
"0496xxxx",
"049xxxxx",
"04xxxxxx",
"0xxxxxxx"
],
"data_quality_errors_tags": [],
"ingredients_that_may_be_from_palm_oil_n": 0,
"categories_hierarchy": [
"en:beverages",
"en:carbonated-drinks",
"en:sodas",
"en:colas",
"en:sweetened-beverages"
],
"serving_quantity": "355",
"traces_from_ingredients": "",
"selected_images": {
"front": {
"display": {
"en": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.400.jpg"
},
"small": {
"en": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.200.jpg"
},
"thumb": {
"en": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.100.jpg"
}
},
"ingredients": {
"thumb": {
"en": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.100.jpg"
},
"display": {
"en": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.400.jpg"
},
"small": {
"en": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.200.jpg"
}
},
"nutrition": {
"small": {
"en": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.200.jpg"
},
"display": {
"en": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.400.jpg"
},
"thumb": {
"en": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.100.jpg"
}
}
},
"image_ingredients_thumb_url": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.100.jpg",
"image_nutrition_small_url": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.200.jpg",
"vitamins_tags": [],
"labels_prev_hierarchy": [],
"ingredients_text_with_allergens_en": "Carbonated Water, High Fructose Corn Syrup, Caramel Color, Phosphoric Acid, Natural Flavors, Caffeine",
"serving_size_debug_tags": [],
"brands_tags": [
"coca-cola"
],
"additives_old_n": 1,
"lang": "en",
"other_nutritional_substances_tags": [],
"editors": [
"",
"tacinte",
"stephane"
],
"ingredients_text_en": "Carbonated Water, High Fructose Corn Syrup, Caramel Color, Phosphoric Acid, Natural Flavors, Caffeine",
"languages": {
"en:english": 5
},
"nutriscore_points": {
"sugars": 8,
"fiber_value": 0,
"saturated_fat_ratio": 0,
"saturated_fat_ratio_value": 0,
"fruits_vegetables_nuts_colza_walnut_olive_oils_value": 0,
"fruits_vegetables_nuts_colza_walnut_olive_oils": 0,
"positive_points": 0,
"saturated_fat_value": 0,
"sodium_value": 12.9,
"fiber": 0,
"energy_value": 165,
"energy": 6,
"proteins_value": 0,
"proteins": 0,
"negative_points": 14,
"sugars_value": 11,
"saturated_fat": 0,
"sodium": 0
},
"traces_debug_tags": [],
"quantity_debug_tags": [],
"product_name_en_debug_tags": [],
"cities_tags": [],
"new_additives_n": 1,
"ingredients_original_tags": [
"en:carbonated-water",
"en:high-fructose-corn-syrup",
"en:e150a",
"en:e338",
"en:caffeine",
"en:natural-flavouring"
],
"nutriments": {
"nutrition-score-uk_100g": 2,
"nova-group_100g": 1.13,
"saturated-fat": 0,
"energy_100g": 165,
"carbohydrates_100g": 11,
"nutrition-score-fr_100g": 14,
"salt_100g": 0.0322,
"proteins_unit": "g",
"carbohydrates": 39,
"fat": 0,
"energy_value": 140,
"sugars_100g": 11,
"saturated-fat_serving": 0,
"proteins_serving": 0,
"salt_value": 0.1143,
"salt_serving": 0.1143,
"nova-group": 4,
"sodium": 0.04572,
"sugars_value": 39,
"nova-group_serving": 4,
"proteins": 0,
"fat_serving": 0,
"fat_value": 0,
"carbohydrates_unit": "g",
"sugars": 39,
"sodium_serving": 0.04572,
"fat_100g": 0,
"carbohydrates_value": 39,
"energy_serving": 586,
"sodium_100g": 0.0129,
"nutrition-score-fr": 14,
"sodium_value": 0.04572,
"sugars_serving": 39,
"carbohydrates_serving": 39,
"saturated-fat_100g": 0,
"salt": 0.1143,
"energy_unit": "kcal",
"salt_unit": "g",
"saturated-fat_value": 0,
"nutrition-score-uk": 2,
"saturated-fat_unit": "g",
"proteins_value": 0,
"energy": 586,
"fat_unit": "g",
"sodium_unit": "g",
"sugars_unit": "g",
"proteins_100g": 0
},
"minerals_tags": [],
"purchase_places": "Chicago,Illinois,USA",
"nutrition_data_prepared": "",
"categories_lc": "en",
"countries_tags": [
"en:united-states"
],
"nutrition_data_per": "serving",
"expiration_date_debug_tags": [],
"completed_t": 1421397673,
"purchase_places_tags": [
"chicago",
"illinois",
"usa"
],
"nutrition_data": "on",
"generic_name_en_debug_tags": [],
"emb_codes_tags": [],
"nucleotides_tags": [],
"allergens_tags": [],
"nutrition_grades_tags": [
"e"
],
"labels_prev_tags": [],
"pnns_groups_2_tags": [
"sweetened-beverages",
"known"
],
"complete": 1,
"image_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.400.jpg",
"additives_old_tags": [
"en:e150c"
],
"entry_dates_tags": [
"2013-08-01",
"2013-08",
"2013"
],
"informers_tags": [
"openfoodfacts-contributors",
"tacinte",
"stephane"
],
"countries_hierarchy": [
"en:united-states"
],
"purchase_places_debug_tags": [],
"manufacturing_places": "",
"image_nutrition_url": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.400.jpg",
"last_image_t": 1478331702,
"nutrition_grade_fr": "e",
"nutriscore_grade": "e",
"nutrition_grades": "e",
"amino_acids_tags": [],
"ingredients_text_en_debug_tags": [],
"additives_original_tags": [
"en:e150c",
"en:e338"
],
"image_ingredients_small_url": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.200.jpg",
"nutrition_data_prepared_per_debug_tags": [],
"ingredients_debug": [
"Carbonated Water",
",",
null,
null,
null,
" High Fructose Corn Syrup",
",",
null,
null,
null,
" Caramel Color",
",",
null,
null,
null,
" Phosphoric Acid",
",",
null,
null,
null,
" ",
":",
":",
null,
null,
" Natural Flavors ",
":",
":",
null,
null,
" ",
",",
null,
null,
null,
" Caffeine"
],
"link_debug_tags": [],
"emb_codes": "",
"product_name_en": "Coca-Cola",
"ingredients_from_palm_oil_tags": [],
"allergens_debug_tags": [],
"additives_tags": [
"en:e150c",
"en:e338"
],
"ingredients_tags": [
"en:carbonated-water",
"en:water",
"en:high-fructose-corn-syrup",
"en:glucose",
"en:fructose",
"en:corn-syrup",
"en:glucose-fructose-syrup",
"en:e150a",
"en:e338",
"en:caffeine",
"en:natural-flavouring",
"en:flavouring"
],
"origins_debug_tags": [],
"data_quality_info_tags": [
"en:nutriscore-computations-same-score",
"en:nutriscore-computations-same-grade"
],
"image_nutrition_thumb_url": "https://static.openfoodfacts.org/images/products/04963406/nutrition_en.9.100.jpg",
"stores_debug_tags": [],
"ingredients_that_may_be_from_palm_oil_tags": [],
"product_quantity": "360",
"allergens": "",
"additives_prev_original_tags": [
"en:e150a",
"en:e338"
],
"generic_name": "",
"lc": "en",
"languages_tags": [
"en:english",
"en:1"
],
"image_front_small_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.200.jpg",
"labels": "",
"nova_groups_tags": [
"en:4-ultra-processed-food-and-drink-products"
],
"categories_tags": [
"en:beverages",
"en:carbonated-drinks",
"en:sodas",
"en:colas",
"en:sweetened-beverages",
"en:non-alcoholic-beverages"
],
"ingredients": [
{
"text": "Carbonated Water",
"vegan": "yes",
"rank": 1,
"vegetarian": "yes",
"id": "en:carbonated-water"
},
{
"text": "High Fructose Corn Syrup",
"vegan": "yes",
"rank": 2,
"vegetarian": "yes",
"id": "en:high-fructose-corn-syrup"
},
{
"text": "Caramel Color",
"id": "en:e150a",
"vegetarian": "yes",
"vegan": "yes",
"rank": 3
},
{
"vegetarian": "yes",
"vegan": "yes",
"rank": 4,
"id": "en:e338",
"text": "Phosphoric Acid"
},
{
"text": "Caffeine",
"vegetarian": "yes",
"vegan": "yes",
"rank": 5,
"id": "en:caffeine"
},
{
"id": "en:natural-flavouring",
"vegetarian": "maybe",
"vegan": "maybe",
"text": "Natural Flavors"
}
],
"scans_n": 23,
"ingredients_n_tags": [
"6",
"1-10"
],
"languages_codes": {
"en": 5
},
"nova_group": "4",
"debug_param_sorted_langs": [
"en"
],
"states_tags": [
"en:to-be-checked",
"en:complete",
"en:nutrition-facts-completed",
"en:ingredients-completed",
"en:expiration-date-to-be-completed",
"en:packaging-code-to-be-completed",
"en:characteristics-completed",
"en:categories-completed",
"en:brands-completed",
"en:packaging-completed",
"en:quantity-completed",
"en:product-name-completed",
"en:photos-validated",
"en:photos-uploaded"
],
"popularity_tags": [
"top-50000-scans-2019",
"top-100000-scans-2019",
"at-least-5-scans-2019",
"at-least-10-scans-2019",
"top-country-us-scans-2019",
"at-least-5-us-scans-2019",
"at-least-10-us-scans-2019"
],
"traces_from_user": "(en)",
"amino_acids_prev_tags": [],
"nova_groups": "4",
"brands_debug_tags": [],
"checkers_tags": [],
"vitamins_prev_tags": [],
"traces_tags": [],
"last_image_dates_tags": [
"2016-11-05",
"2016-11",
"2016"
],
"ingredients_text_debug": "Carbonated Water, High Fructose Corn Syrup, Caramel Color, Phosphoric Acid, : Natural Flavors : , Caffeine",
"_id": "04963406",
"additives_debug_tags": [],
"ingredients_text_with_allergens": "Carbonated Water, High Fructose Corn Syrup, Caramel Color, Phosphoric Acid, Natural Flavors, Caffeine",
"lang_debug_tags": [],
"_keywords": [
"coca",
"beverage",
"cola",
"coca-cola",
"carbonated",
"drink",
"soda",
"sugared"
],
"image_small_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.200.jpg",
"interface_version_modified": "20120622",
"unknown_nutrients_tags": [],
"brands": "Coca Cola",
"origins": "",
"nutrition_data_prepared_per": "100g",
"labels_tags": [],
"update_key": "quality2",
"fruits-vegetables-nuts_100g_estimate": 0,
"data_quality_bugs_tags": [],
"data_quality_warnings_tags": [],
"countries_debug_tags": [],
"ingredients_analysis_tags": [
"en:palm-oil-free",
"en:maybe-vegan",
"en:maybe-vegetarian"
],
"image_front_thumb_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.100.jpg",
"last_modified_by": "cc0000",
"nucleotides_prev_tags": [],
"traces": "",
"nutriscore_score": 14,
"unique_scans_n": 19,
"pnns_groups_2": "Sweetened beverages",
"countries_lc": "en",
"last_editor": "cc0000",
"no_nutrition_data": "",
"additives_tags_n": null,
"categories": "Beverages, Carbonated drinks, Sodas, Colas, Sweetened beverages",
"ingredients_from_or_that_may_be_from_palm_oil_n": 0,
"ingredients_hierarchy": [
"en:carbonated-water",
"en:water",
"en:high-fructose-corn-syrup",
"en:glucose",
"en:fructose",
"en:corn-syrup",
"en:glucose-fructose-syrup",
"en:e150a",
"en:e338",
"en:caffeine",
"en:natural-flavouring",
"en:flavouring"
],
"manufacturing_places_debug_tags": [],
"minerals_prev_tags": [],
"manufacturing_places_tags": [],
"expiration_date": "",
"sortkey": 301540096187,
"serving_size": "355 ml",
"photographers_tags": [
"openfoodfacts-contributors",
"tacinte",
"stephane",
"alexfloresveliz"
],
"countries": "United States",
"nutrition_score_warning_no_fruits_vegetables_nuts": 1,
"image_ingredients_url": "https://static.openfoodfacts.org/images/products/04963406/ingredients_en.10.400.jpg",
"interface_version_created": "20130323.jqm",
"emb_codes_debug_tags": [],
"last_modified_t": 1540096187,
"states": "en:to-be-checked, en:complete, en:nutrition-facts-completed, en:ingredients-completed, en:expiration-date-to-be-completed, en:packaging-code-to-be-completed, en:characteristics-completed, en:categories-completed, en:brands-completed, en:packaging-completed, en:quantity-completed, en:product-name-completed, en:photos-validated, en:photos-uploaded",
"ingredients_text": "Carbonated Water, High Fructose Corn Syrup, Caramel Color, Phosphoric Acid, Natural Flavors, Caffeine",
"origins_tags": [],
"nutrient_levels_tags": [
"en:fat-in-low-quantity",
"en:saturated-fat-in-low-quantity",
"en:sugars-in-high-quantity",
"en:salt-in-low-quantity"
],
"code": "04963406",
"id": "04963406",
"link": "",
"traces_hierarchy": [],
"unknown_ingredients_n": 0,
"data_quality_tags": [
"en:nutriscore-computations-same-score",
"en:nutriscore-computations-same-grade"
],
"labels_lc": "en",
"ingredients_ids_debug": [
"carbonated-water",
"high-fructose-corn-syrup",
"caramel-color",
"phosphoric-acid",
"natural-flavors",
"caffeine"
],
"stores_tags": [],
"compared_to_category": "en:non-alcoholic-beverages",
"allergens_hierarchy": [],
"max_imgid": "11",
"emb_codes_20141016": "",
"misc_tags": [
"en:nutrition-no-fruits-vegetables-nuts",
"en:nutrition-no-fiber-or-fruits-vegetables-nuts",
"en:nutriscore-computed"
],
"languages_hierarchy": [
"en:english"
],
"images": {
"1": {
"uploaded_t": 1375384725,
"uploader": "openfoodfacts-contributors",
"sizes": {
"100": {
"h": 100,
"w": 75
},
"400": {
"w": 300,
"h": 400
},
"full": {
"h": 3264,
"w": 2448
}
}
},
"2": {
"sizes": {
"100": {
"h": 100,
"w": 74
},
"400": {
"h": 400,
"w": 297
},
"full": {
"h": 4208,
"w": 3120
}
},
"uploaded_t": 1421397406,
"uploader": "tacinte"
},
"3": {
"sizes": {
"100": {
"w": 74,
"h": 100
},
"400": {
"h": 400,
"w": 297
},
"full": {
"h": 4208,
"w": 3120
}
},
"uploader": "tacinte",
"uploaded_t": 1421397412
},
"4": {
"sizes": {
"100": {
"w": 74,
"h": 100
},
"400": {
"w": 297,
"h": 400
},
"full": {
"h": 4208,
"w": 3120
}
},
"uploader": "tacinte",
"uploaded_t": 1421397413
},
"5": {
"sizes": {
"100": {
"w": 100,
"h": 75
},
"400": {
"w": 400,
"h": 300
},
"full": {
"h": 2448,
"w": 3264
}
},
"uploader": "stephane",
"uploaded_t": "1374776967"
},
"6": {
"sizes": {
"100": {
"h": 75,
"w": 100
},
"400": {
"w": 400,
"h": 300
},
"full": {
"w": 3264,
"h": 2448
}
},
"uploader": "stephane",
"uploaded_t": "1374776970"
},
"7": {
"uploader": "stephane",
"uploaded_t": "1374776974",
"sizes": {
"100": {
"h": 75,
"w": 100
},
"400": {
"w": 400,
"h": 300
},
"full": {
"w": 3264,
"h": 2448
}
}
},
"8": {
"sizes": {
"100": {
"h": 75,
"w": 100
},
"400": {
"h": 300,
"w": 400
},
"full": {
"w": 3264,
"h": 2448
}
},
"uploaded_t": "1374776980",
"uploader": "stephane"
},
"9": {
"sizes": {
"100": {
"h": 75,
"w": 100
},
"400": {
"h": 300,
"w": 400
},
"full": {
"w": 3264,
"h": 2448
}
},
"uploaded_t": "1374776984",
"uploader": "stephane"
},
"10": {
"uploader": "stephane",
"uploaded_t": "1374776998",
"sizes": {
"100": {
"h": 75,
"w": 100
},
"400": {
"h": 300,
"w": 400
},
"full": {
"h": 2448,
"w": 3264
}
}
},
"11": {
"uploader": "alexfloresveliz",
"uploaded_t": "1478331702",
"sizes": {
"100": {
"h": 100,
"w": 58
},
"400": {
"w": 233,
"h": 400
},
"full": {
"h": 516,
"w": 300
}
}
},
"ingredients_en": {
"rev": "10",
"geometry": "1355x473-777-2377",
"normalize": null,
"sizes": {
"100": {
"h": 35,
"w": 100
},
"200": {
"w": 200,
"h": 70
},
"400": {
"w": 400,
"h": 140
},
"full": {
"w": 1355,
"h": 473
}
},
"white_magic": null,
"imgid": "3"
},
"nutrition_en": {
"rev": "9",
"geometry": "1303x2325-798-147",
"normalize": "checked",
"sizes": {
"100": {
"h": 100,
"w": 56
},
"200": {
"h": 200,
"w": 112
},
"400": {
"h": 400,
"w": 224
},
"full": {
"h": 2325,
"w": 1303
}
},
"white_magic": null,
"imgid": "3"
},
"ingredients": {
"rev": "10",
"geometry": "1355x473-777-2377",
"normalize": null,
"sizes": {
"100": {
"h": 35,
"w": 100
},
"200": {
"w": 200,
"h": 70
},
"400": {
"w": 400,
"h": 140
},
"full": {
"w": 1355,
"h": 473
}
},
"white_magic": null,
"imgid": "3"
},
"front": {
"imgid": "2",
"white_magic": null,
"sizes": {
"100": {
"h": 100,
"w": 53
},
"200": {
"h": 200,
"w": 106
},
"400": {
"h": 400,
"w": 212
},
"full": {
"w": 2027,
"h": 3819
}
},
"normalize": null,
"geometry": "2027x3819-546-94",
"rev": "8"
},
"nutrition": {
"rev": "9",
"geometry": "1303x2325-798-147",
"normalize": "checked",
"sizes": {
"100": {
"h": 100,
"w": 56
},
"200": {
"h": 200,
"w": 112
},
"400": {
"h": 400,
"w": 224
},
"full": {
"h": 2325,
"w": 1303
}
},
"white_magic": null,
"imgid": "3"
},
"front_en": {
"imgid": "11",
"angle": "0",
"y2": "0",
"normalize": "false",
"white_magic": "false",
"sizes": {
"100": {
"w": 58,
"h": 100
},
"200": {
"h": 200,
"w": 116
},
"400": {
"w": 233,
"h": 400
},
"full": {
"h": 516,
"w": 300
}
},
"geometry": "0x0-0-0",
"y1": "0",
"x2": "0",
"x1": "0",
"rev": "21"
}
},
"stores": "",
"nutrient_levels": {
"saturated-fat": "low",
"sugars": "high",
"salt": "low",
"fat": "low"
},
"nutrition_score_beverage": 1,
"correctors_tags": [
"tacinte",
"alexfloresveliz",
"cc0000"
],
"rev": 23,
"pnns_groups_1_tags": [
"beverages",
"known"
],
"labels_hierarchy": [],
"generic_name_en": "",
"quantity": "12 fl oz (355 ml)",
"packaging_debug_tags": [],
"image_front_url": "https://static.openfoodfacts.org/images/products/04963406/front_en.21.400.jpg",
"creator": "openfoodfacts-contributors",
"states_hierarchy": [
"en:to-be-checked",
"en:complete",
"en:nutrition-facts-completed",
"en:ingredients-completed",
"en:expiration-date-to-be-completed",
"en:packaging-code-to-be-completed",
"en:characteristics-completed",
"en:categories-completed",
"en:brands-completed",
"en:packaging-completed",
"en:quantity-completed",
"en:product-name-completed",
"en:photos-validated",
"en:photos-uploaded"
],
"product_name": "Coca-Cola",
"emb_codes_orig": "",
"nutrition_data_per_debug_tags": [],
"nutrition_score_debug": " -- in beverages category - a_points_fr_beverage: 6 (energy) + 0 (sat_fat) + 8 (sugars) + 0 (sodium) = 14 - -- energy 0 + sat-fat 0 + fr-sat-fat-for-fats 0 + sugars 2 + sodium 0 - fruits 0% 0 - fiber 0 - proteins 0 -- fsa 2 -- fr 14",
"editors_tags": [
"alexfloresveliz",
"tacinte",
"cc0000",
"openfoodfacts-contributors",
"stephane"
],
"allergens_from_user": "(en)",
"packaging_tags": [
"can-metal"
],
"created_t": 1375384688,
"allergens_from_ingredients": ""
},
"status": 1,
"code": "04963406"
}Code:
200
The Robotoff project is intended to complete missing information of products by prompting users to confirm predictions inferred by Artificial Intelligence algorithms. These algorithms are calculated based on “insights”, which are facts about a product that have been extracted or deduced from the product pictures, ingredients, categories, labels, etc…
The project URL is: https://robotoff.openfoodfacts.org/api/v1/{endpoint}.
Robotoff can interact with all Open Food Facts products and environments. The server_domain field must be used to specify the product/environment (api.openfoodfacts.org for OFF-prod).
To configure this feature in your app follow the steps below:
Fetch a JSON file when opening a product. Example: https://robotoff.openfoodfacts.org/api/v1/questions/3274570800026?lang=en&count=3
{"questions": [{"barcode": "3274570800026", "type": "add-binary", "value": "Scallop", "question": "Does the product belong to this category?", "insight_id": "5cac03bc-a5a7-4ec2-a548-17fd9319fee7", "insight_type": "category", "source_image_url": "https://static.openfoodfacts.org/images/products/327/457/080/0026/front_en.4.400.jpg"}], "status": "found"}
Display the question and possible answers in the UI.
Send back the proper ping to the Open Food Facts server if the user answers.
https://github.com/openfoodfacts/robotoff/blob/master/doc/api.md
Fetch a random insight.
type (string, optional): The type of insight. If not provided, an insight from any type will be returned.
country (string, optional): Only return predictions with products from a specific country (ex: en:france)
value_tag (string, optional): Filter by value tag, i.e the value that is going to be sent to Open Food Facts.
server_domain (string, optional): Server domain. Default to ‘api.openfoodfacts.org’
insight_id: ID of the insightReturn all insights associated with a specific product.
barcode: Product barcodeserver_domain (string, optional) - server domain. Default to ‘api.openfoodfacts.org’ocr_url (string, required): the url of the OCR JSONResponse 200 (application/json)
{
“nutrients”: {
“glucid”: [
{
“nutrient”: “glucid”,
“raw”: “glucides 53 g”,
“unit”: “g”,
“value”: “53”
}
]
}
}
You can get questions for a given product or get random questions.
barcode: Product barcodelang (string, optional): the language of the question/value. Default: en.count (integer, optional): Number of questions to return. Default: 1.server_domain (string, optional): server domain. Default: ‘api.openfoodfacts.org’lang (string, optional): the language of the question/value. Default: en.count (integer, optional): Number of questions to return. Default: 1.insight_types (list, optional): comma-separated list, filter by insight types.country (string, optional): filter by country tag.brands (string, optional): filter by brands, comma-separated list of brand tags.value_tag (string, optional): filter by value tag, i.e the value that is going to be sent to Openfoodfacts.server_domain (string, optional): server domain. Default: api.openfoodfacts.org.text (string, required) - the ingredient text to spellcheck.Response 200 (application/json)
{
“corrected”: “farine de blé”,
“corrections”: [
{
“score”: 0.0009564351,
“term_corrections”: [
{
“correction”: “farine”,
“end_offset”: 6,
“original”: “fqrine”,
“start_offset”: 0
}
]
}
],
“text”: “fqrine de blé”
}
Submit an annotation, given the insight_id. The request type must be application/x-www-form-urlencoded.
insight_id (string, required): ID of the insightannotation (integer, required):
Annotation of the prediction:update (integer, optional): Send the update to Open Food Facts if update=1. Otherwise, the update won’t be sent. This parameter is useful if the update is performed client-side.Search requests allow you to retrieve the nutritional data of products that comply with your search criteria.
To do so, you combine tags to get custom results. This lets you create thousands of custom APIs for your use case.
Important! The search feature only works on whole words, not parts of words. Your application should not have “search as you type” features that send search queries with parts of words, since this causes performance issues on the Open Food Facts server.
The search URL you have to use always starts with:
search_url = “https://world.openfoodfacts.org/cgi/search.pl?
You can basically use all the parameters you would use in an advanced search on the site: [https://world.openfoodfacts.org/cgi/search.pl?action=display&sort_by=unique_scans_n&page_size=20&action=display graphical advanced search on the site]
There are three types of parameters you can use to filter the results:
Note: You can find a list of supported parameters and an example of a full JSON response in the Parameters section.
Every time you use a criterion in your query, you must use the following tags:
tagtype_0=categoriestag_contains_0=containstag_0=cerealsWhere tagtype_0 can be one of the following:
brandscategoriespackaginglabelsoriginsmanufacturing_placesemb_codespurchase_placesstorescountriesadditivesallergenstracesnutrition_gradesstatescontainsdoes_not_containIf you want to add more criteria to the query, increase the number of the tag. For example:
tagtype_0=categoriestag_contains_0=containstag_0=cerealstagtype_1=labeltag_contains_1=containstag_1=kosherUse the following parameters to include or exclude products containing any additives or ingredients from palm oil:
additives
without_additiveswith_additivesindifferent_additivesingredients_from_palm_oil
withoutwithindifferentingredients_that_may_be_from_palm_oil
withoutwithindifferentingredients_from_or_that_may_be_from_palm_oil
withoutwithindifferentYou can also filter by nutriments (fat, sugars, energy, etc). To do so, you need to add three different parameters for each nutriment:
Example:
nutriment_0=energynutriment_compare_0=ltnutriment_value_0=500You can enter the following categories (nutriment_0): https://static.openfoodfacts.org/data/taxonomies/nutrients.json
Comparison of nutrients
Nutriment to compare
nutriment_compare_0
Operator
lt # less thanlte # less than or equalgt # greater thangte # greater than or equaleq # equal tonutriment_value_0 - Value to compare the nutrients toOther search parameters: Output
sort_by # sort byunique_scans_n # Popularityproduct_name # Product namecreated_t # Add datelast_modified_t # Edit dateResults per page
page_size # page_size
Pagination * page=1
Format * json=true (recommended) * xml=true
Linked Data
Whenever possible, Open Food Facts entities are linked to Wikidata, and in turn to Wikipedia. What this means is that you get access to a trove of additional encyclopedic knowledge about food. You can for instance get: Wikipedia articles about Camembert, the translation of salt in many languages, the molecular structure of a cosmetic ingredient… We provide the Wikidata QID, which is an unambiguous, stable and reliable identifier for a concept that will be useful to actually retrieve info from Wikipedia and Wikidata.
Example
https://world.openfoodfacts.org/categories.json
{"linkeddata":{"wikidata:en":"Q40050"},"url":"https://world.openfoodfacts.org/category/beverages","name":"Beverages","id":"en:beverages","products":14196}
Beverages >> https://world.openfoodfacts.org/category/beverages >> Q40050 >> https://www.wikidata.org/wiki/Q40050
You can use the Wikipedia and Wikidata APIs to get the information you want
GET requests allow you to make two types of calls: READ and SEARCH. This scenario describes how to make a GET SEARCH call to retrieve the nutritional data of products that comply with your search criteria.
Meet Dave. Dave is an Open Food Facts contributor and a developer. He wants to build HealthyFoodChoices, an Android app aimed at concious consumers that buy local and healthy products.
HealthyFoodChoices will provide information on healthy foods by country. The users can narrow down the results by applying different filters and save their search criteria so that the app shows them the products that match their preferences next time they use it.
To identify the potential users’ needs, Dave has met with some concious consumers. Anna is one of them. This 36-year old New Yorker follows a plant-based diet and wants to avoid the intake of palm oil. She wants to find a breakfast cereal brand that does not use palm oil or additives and has a good nutriscore (A).
To make the API query that returns the products that might be interesting for Anna, Dave doesn’t need to authenticate. However, he has to add a User-Agent HTTP Header with the name of his app, the version, system and a url (if any), not to be blocked by mistake.
In this case, that would be: User-Agent: HealthyFoodChoices - Android - Version 1.0
Since Anna lives in NY, Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).
The country code determines that only the products sold in the US are displayed. The language of the interface for the country code US is English.
In this case:
Dave wants to fine-tune the query to provide Anna with the products that match her buying preferences. To do so, he wants to drill down the results to display only breakfast cereals.
First, he adds the following sequence after the https call: /cgi/search.pl? (all search queries need to include this)
Then, he defines some tags and the apropriate values: action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals
where:
action introduces the action to be performed (process)tagtype_0 adds the first search criterion (categories)tag_contains_0=contains determines that the results should be included (note that you can exclude products from the search)tag_0 defines the category to be filtered by (breakfast_cereals)Note: The parameters are concatenated with &
To retrieve breakfast cereals sold in the US, Dave makes the following call: https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals
With this query, the nutrition facts of more than 200 products are displayed.
Then, Dave wants to exclude the products that contain ingredients from palm oil. He adds a new parameter to the query:
ingredients_from_palm_oil=withoutThis parameter excludes the products that might contain palm oil ingredients from the search.
Next, Dave adds another parameter to exclude the products that contain additives:
additives=withoutThe query is as follows:
Finally, Dave adds another parameter to include only products with a nutriscore A. The nutriscore is a nutrition grade determined by the amount of healthy and unhealthy nutrients.
tagtype_1=nutrition_gradetag_contains_1=containstag_1=AThe complete query looks like this:
Add the json=true parameter to avoid scraping.
Anna can see now at a glance which products match her search criteria. In this case, around 20 brands of breakfast cereals.
| Key | Value | Description |
|---|---|---|
| action | process | |
| tagtype_0 | categories | |
| tag_contains_0 | contains | |
| tag_0 | breakfast_cereals | |
| tagtype_1 | nutrition_grades | |
| tag_contains_1 | contains | |
| tag_1 | A | |
| additives | without | |
| ingredients_from_palm_oil | without |
| Key | Value | Description |
|---|---|---|
| action | process | |
| tagtype_0 | categories | |
| tag_contains_0 | contains | |
| tag_0 | breakfast_cereals | |
| tagtype_1 | nutrition_grades | |
| tag_contains_1 | contains | |
| tag_1 | A | |
| additives | without | |
| ingredients_from_palm_oil | without | |
| json | true |
You can use the following query to retrieve the Nova Groups taxonomy:
GET https://world.openfoodfacts.org/data/taxonomies/additives_classes.json
You can use the following query to retrieve the additives taxonomy:
GET https://world.openfoodfacts.org/data/taxonomies/additives.json
Use the following query to retrieve the additives facet:
GET http://world.openfoodfacts.org/additives.json
The response includes the code and name of the additive, a link to a Wikipedia page with more information about the additive, and the number of products containing this additive in the Open Food Facts database.
You can drill-down to the list of products containing a certain additive by making the following call:
GET https://world.openfoodfacts.org/additive/additivecode-additivename.json
Example:
GET https://world.openfoodfacts.org/additive/e322-lecithins.json
You can use the following query to retrieve the allergens taxonomy:
GET https://world.openfoodfacts.org/data/taxonomies/allergens.json
Use the following query to retrieve the allergens facet:
GET https://world.openfoodfacts.org/allergens.json
You can use the following query to retrieve the brands taxonomy:
GET https://world.openfoodfacts.org/data/taxonomies/brands.json
Use the following query to retrieve the brands facet:
GET https://world.openfoodfacts.org/brands.json